Resimulation and counterfactuals ===================================== .. index:: resimulation, counterfactual, Shapley, Viterbi, FFBS Given a solved model and a filter output, the ``resim_bridge`` package reconstructs the latent regime path and structural shock sequence consistent with the observed data, then re-simulates under user-chosen perturbations. Five reconstruction methods are exposed; three decomposition utilities consume the reconstructed baseline. The bridge does **not** modify ``filter(m)``, the solver, or any class method. It reads the filter output and dispatches into the underlying ``+resim`` package (also under ``classes/utils/``). Adapter ------------- ``resim_bridge.adapt`` packages the model and filter output into the canonical tuple used by every reconstruction method:: adapter = resim_bridge.adapt(m, f); The returned struct exposes: .. list-table:: :header-rows: 1 :widths: 25 75 * - Field - Meaning * - ``Tfunc(x, eps, r)`` - One-step state propagator on the full endogenous vector. * - ``Pfunc(x)`` - ``(h x h)`` regime transition matrix at state ``x``. Constant for exogenous Markov chains; state-dependent for endogenous TVTPs. * - ``smoothed.x`` - ``(nx x h x T)`` regime-conditional smoothed state means. * - ``smoothed.eps`` - ``(ne x h x T)`` regime-conditional smoothed shocks. * - ``smoothed.pi`` - ``(h x T)`` smoothed regime probabilities. * - ``alpha`` - ``(h x T)`` filtered regime probabilities (self-normalised inside the methods). * - ``pi0`` - ``(h x 1)`` initial regime distribution. * - ``x0`` - ``(nx x 1)`` pi-weighted initial state. Reconstruction methods ------------------------ ``resim_bridge.run(m, f, method, opts)`` dispatches over four deterministic / stochastic reconstruction methods: .. list-table:: :header-rows: 1 :widths: 25 75 * - ``method`` - What it returns * - ``'viterbi'`` - The MAP regime path (single deterministic sequence) and the state path obtained by forward-simulating along it with the regime-conditional smoothed shocks. * - ``'ffbs'`` - ``M`` draws from the posterior regime-path distribution via forward-filter backward-sample. Exact up to filter approximation. * - ``'independent'`` - ``M`` regime paths drawn independently at each date from the smoothed marginals. Ignores the transition law; correct only marginally. Useful for fast exploratory analysis. * - ``'rao_blackwell'`` - Deterministic pi-weighted mixture across regimes. Exact for linear models; biased for nonlinear ones, with bias growing in regime uncertainty. The ``'particle'`` method requires a particle-filter output rather than a Kalman smoother; ``run`` raises ``resim_bridge:run:notWired`` in that case. Call ``resim.particle`` directly with a particle container. Counterfactuals --------------- ``resim_bridge.counterfactual(m, f, mode, spec)`` reconstructs a deterministic baseline and re-simulates under one of three perturbations: .. list-table:: :header-rows: 1 :widths: 15 30 55 * - ``mode`` - ``spec`` fields - Effect * - ``'shock'`` - ``shock_ids``, optional ``values`` - Zeroes (or replaces) the listed shocks on the reconstructed baseline; the regime path is held fixed. * - ``'regime'`` - ``r_path`` - Replaces the reconstructed regime path with a user-supplied sequence; shocks held fixed. * - ``'param'`` - ``parameters`` struct - Re-sets parameters, re-solves, re-filters on the same data, and re-runs the reconstruction. The return struct carries ``baseline``, ``counter``, and ``delta`` ``= counter.x - baseline.x``. Shock decompositions ---------------------- Two flavours, both along the reconstructed regime path: ``resim_bridge.shock_decomp(m, f)`` -- leave-one-out:: delta_k(t) = x_t^full - x_t^(-k) Exact for linear models; the interaction residual is not allocated. ``resim_bridge.shapley(m, f)`` -- Shapley:: phi_k(t) = (1/ne!) sum_sigma [ v(S U {k}, t) - v(S, t) ] The Shapley decomposition is **exactly additive** even for nonlinear models:: sum_k phi_k(t) = x_t^full - x_t^base Exact mode enumerates all :math:`2^{n_e}` subsets and runs for ``ne <= opts.exact_threshold`` (default 10). Sampled mode (:cite:`CastroGomezTejada2009`) is used otherwise. Ergodic variance decomposition ------------------------------- ``resim_bridge.var_decomp(m, kind)`` works at the model's ergodic distribution; it does not need ``f``. Three games: .. list-table:: :header-rows: 1 :widths: 15 85 * - ``kind`` - Decomposition * - ``'shocks'`` - Shapley allocation of total variance across the ``ne`` shocks. The regime process runs freely under ``Pfunc``. * - ``'joint'`` - Shapley allocation across the ``ne`` shocks and a ``regime`` player. Removing the regime player fixes the chain at its ergodic distribution via ``Pfunc_erg``. * - ``'anova'`` - Between-vs-within decomposition via the law of total variance:: Var(x) = W + B where ``W = sum_j pi_j * Var(x | r_t=j)`` and ``B = sum_j pi_j * (mu_j - mu)(mu_j - mu)'``. Always exact; no Shapley enumeration. A worked example using a switching New-Keynesian model is provided in *Chapter 22 - Nonlinear filtering under regime switching* of the RISE lecture notes (``T22_6_Resimulation.m``). API reference ---------------- .. todo:: Per-method autodoc stubs for the ``+resim_bridge`` package are not yet generated. ``Docs/auxiliary_rst_docfiles_maker.m`` does not currently crawl ``+resim_bridge``; wire it and regenerate ``resim_bridge_adapt.rst``, ``resim_bridge_run.rst``, ``resim_bridge_counterfactual.rst``, ``resim_bridge_shock_decomp.rst``, ``resim_bridge_shapley.rst``, ``resim_bridge_var_decomp.rst``, then re-enable the includes below. .. Re-enable the include block below once the +resim_bridge crawler is wired into auxiliary_rst_docfiles_maker.m and produces the per-method stub files: include:: resim_bridge_adapt.rst include:: resim_bridge_run.rst include:: resim_bridge_counterfactual.rst include:: resim_bridge_shock_decomp.rst include:: resim_bridge_shapley.rst include:: resim_bridge_var_decomp.rst